package cn.iocoder.yudao.module.system.service.useractivity;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.system.dal.dataobject.useractivity.UserActivityStatsDO;
import cn.iocoder.yudao.module.system.dal.dataobject.useractivity.UserDailyActivityDO;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;

/**
 * 用户活跃度统计 Service 接口
 *
 * @author 系统开发团队
 */
public interface UserActivityStatsService {

    // ========== 统计数据计算 ==========

    /**
     * 计算指定日期的用户活跃度统计
     *
     * @param statDate 统计日期
     * @return 计算结果
     */
    boolean calculateUserActivityStats(LocalDate statDate);

    /**
     * 批量计算用户活跃度统计
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 计算结果
     */
    boolean batchCalculateUserActivityStats(LocalDate startDate, LocalDate endDate);

    /**
     * 重新计算指定日期的统计数据
     *
     * @param statDate 统计日期
     * @return 重新计算结果
     */
    boolean recalculateUserActivityStats(LocalDate statDate);

    /**
     * 计算DAU（日活跃用户数）
     *
     * @param statDate 统计日期
     * @return DAU统计数据
     */
    UserActivityStatsDO calculateDauStats(LocalDate statDate);

    /**
     * 计算WAU（周活跃用户数）
     *
     * @param statDate 统计日期（周的最后一天）
     * @return WAU统计数据
     */
    UserActivityStatsDO calculateWauStats(LocalDate statDate);

    /**
     * 计算MAU（月活跃用户数）
     *
     * @param statDate 统计日期（月的最后一天）
     * @return MAU统计数据
     */
    UserActivityStatsDO calculateMauStats(LocalDate statDate);

    // ========== 统计数据查询 ==========

    /**
     * 分页查询用户活跃度统计
     *
     * @param startDate          开始日期
     * @param endDate            结束日期
     * @param statType           统计类型
     * @param calculationStatus  计算状态
     * @param pageNo             页码
     * @param pageSize           页大小
     * @return 分页结果
     */
    PageResult<UserActivityStatsDO> getUserActivityStatsPage(LocalDate startDate, LocalDate endDate,
                                                             Integer statType, Integer calculationStatus,
                                                             int pageNo, int pageSize);

    /**
     * 获取用户活跃度统计概览
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 统计概览
     */
    Map<String, Object> getUserActivityStatsOverview(LocalDate startDate, LocalDate endDate);

    /**
     * 获取用户活跃度趋势数据
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @param statType  统计类型
     * @return 趋势数据
     */
    List<UserActivityStatsDO> getUserActivityTrend(LocalDate startDate, LocalDate endDate, Integer statType);

    /**
     * 获取指定日期的统计详情
     *
     * @param statDate 统计日期
     * @param statType 统计类型
     * @return 统计详情
     */
    UserActivityStatsDO getUserActivityStatsDetail(LocalDate statDate, Integer statType);

    /**
     * 获取最新的统计数据
     *
     * @param statType 统计类型
     * @param limit    数量限制
     * @return 最新统计数据
     */
    List<UserActivityStatsDO> getLatestUserActivityStats(Integer statType, Integer limit);

    // ========== 用户活跃明细 ==========

    /**
     * 记录用户每日活跃明细
     *
     * @param userId       用户ID
     * @param activityDate 活跃日期
     * @return 活跃明细记录
     */
    UserDailyActivityDO recordUserDailyActivity(Long userId, LocalDate activityDate);

    /**
     * 更新用户每日活跃明细
     *
     * @param userDailyActivity 用户活跃明细
     * @return 更新结果
     */
    boolean updateUserDailyActivity(UserDailyActivityDO userDailyActivity);

    /**
     * 分页查询用户活跃明细
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @param userId    用户ID
     * @param isActive  是否活跃
     * @param userType  用户类型
     * @param pageNo    页码
     * @param pageSize  页大小
     * @return 分页结果
     */
    PageResult<UserDailyActivityDO> getUserDailyActivityPage(LocalDate startDate, LocalDate endDate,
                                                             Long userId, Boolean isActive, Integer userType,
                                                             int pageNo, int pageSize);

    /**
     * 获取用户活跃明细
     *
     * @param userId       用户ID
     * @param activityDate 活跃日期
     * @return 活跃明细
     */
    UserDailyActivityDO getUserDailyActivity(Long id);

    /**
     * 获取指定日期的活跃用户列表
     *
     * @param activityDate 活跃日期
     * @return 活跃用户列表
     */
    List<UserDailyActivityDO> getActiveUsersByDate(LocalDate activityDate);

    /**
     * 获取活跃用户列表
     *
     * @param activityDate 活跃日期
     * @param startDate    开始日期
     * @param endDate      结束日期
     * @param userType     用户类型
     * @param limit        限制数量
     * @return 活跃用户列表
     */
    List<UserDailyActivityDO> getActiveUsers(LocalDate activityDate, LocalDate startDate, LocalDate endDate, Integer userType, Integer limit);

    /**
     * 获取高活跃用户列表
     *
     * @param activityDate     活跃日期
     * @param minFeatureUsage  最小功能使用次数
     * @return 高活跃用户列表
     */
    List<UserDailyActivityDO> getHighActiveUsers(LocalDate startDate, LocalDate endDate, Integer minLoginDays);

    /**
     * 获取回流用户列表
     *
     * @param activityDate 活跃日期
     * @param inactiveDays 非活跃天数
     * @return 回流用户列表
     */
    List<UserDailyActivityDO> getReturnUsers(LocalDate startDate, LocalDate endDate, Integer inactiveDays);

    // ========== 数据分析 ==========

    /**
     * 分析用户活跃度变化
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 活跃度变化分析
     */
    Map<String, Object> analyzeActivityChange(LocalDate startDate, LocalDate endDate, LocalDate compareStartDate, LocalDate compareEndDate);

    /**
     * 分析用户留存情况
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 留存分析
     */
    Map<String, Object> analyzeUserRetention(LocalDate startDate, LocalDate endDate, Integer retentionDays);

    /**
     * 分析用户行为模式
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 行为模式分析
     */
    Map<String, Object> analyzeUserBehaviorPattern(LocalDate startDate, LocalDate endDate);

    // ========== 数据管理 ==========

    /**
     * 删除过期的统计数据
     *
     * @param beforeDate 删除此日期之前的数据
     * @return 删除数量
     */
    int deleteExpiredStats(LocalDate beforeDate);

    /**
     * 删除过期的活跃明细数据
     *
     * @param beforeDate 删除此日期之前的数据
     * @return 删除数量
     */
    int deleteExpiredDailyActivity(LocalDate beforeDate);

    /**
     * 获取计算进度
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 计算进度信息
     */
    Map<String, Object> getCalculationProgress(LocalDate startDate, LocalDate endDate);

    /**
     * 检查数据完整性
     *
     * @param startDate 开始日期
     * @param endDate   结束日期
     * @return 数据完整性检查结果
     */
    Map<String, Object> checkDataIntegrity(LocalDate startDate, LocalDate endDate);
}